<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Writing Composed Operations</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast">
<link rel="up" href="../using_io.html" title="Networking">
<link rel="prev" href="files.html" title="Files">
<link rel="next" href="writing_composed_operations/echo.html" title="Echo 💡">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="files.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_io.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="writing_composed_operations/echo.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="beast.using_io.writing_composed_operations"></a><a class="link" href="writing_composed_operations.html" title="Writing Composed Operations">Writing Composed
      Operations</a>
</h3></div></div></div>
<p>
        Asynchronous operations are started by calling a free function or member
        function known as an asynchronous <span class="emphasis"><em><a href="../../../../../../doc/html/boost_asio/reference/asynchronous_operations.html" target="_top">initiating
        function</a></em></span>. This function accepts parameters specific to
        the operation as well as a <a href="../../../../../../doc/html/boost_asio/reference/asynchronous_operations.html#boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers" target="_top"><span class="emphasis"><em>CompletionToken</em></span></a>.
        The token is either a completion handler, or a type defining how the caller
        is informed of the asynchronous operation result. Networking provides the
        special tokens <a href="../../../../../../doc/html/boost_asio/reference/use_future_t.html" target="_top"><code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">use_future</span></code></a>
        and <a href="../../../../../../doc/html/boost_asio/reference/yield_context.html" target="_top"><code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">yield_context</span></code></a>
        for using futures and coroutines respectively. This system of customizing
        the return value and method of completion notification is known as the <span class="emphasis"><em>Universal
        Asynchronous Model</em></span> described in <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf" target="_top"><span class="bold"><strong>N3747</strong></span></a>, and a built in to <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/n4771.pdf" target="_top">Networking
        TS</a>. Here is an example of an initiating function which reads a line
        from the stream and echoes it back. This function is developed further in
        the next section:
      </p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span>
    <span class="keyword">class</span> <span class="identifier">AsyncStream</span><span class="special">,</span>
    <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">,</span>
    <span class="keyword">class</span> <span class="identifier">CompletionToken</span><span class="special">&gt;</span>
<span class="keyword">auto</span>
<span class="identifier">async_echo</span> <span class="special">(</span><span class="identifier">AsyncStream</span><span class="special">&amp;</span> <span class="identifier">stream</span><span class="special">,</span> <span class="identifier">DynamicBuffer</span><span class="special">&amp;</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">CompletionToken</span><span class="special">&amp;&amp;</span> <span class="identifier">token</span><span class="special">)</span>
</pre>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
          This initiating function receives the dynamic buffer by lvalue-reference,
          instead of by rvalue-reference as specified in networking. An explanation
          for this difference may be found in <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1100r0.html" target="_top">[P1100R0]
          Efficient composition with DynamicBuffer</a>.
        </p></td></tr>
</table></div>
<p>
        Authors using Beast can reuse the library's primitives to create their own
        initiating functions for performing a series of other, intermediate asynchronous
        operations before invoking a final completion handler. The set of intermediate
        actions produced by an initiating function is known as a <a href="http://blog.think-async.com/2009/08/composed-operations-coroutines-and-code.html" target="_top"><span class="emphasis"><em>composed
        operation</em></span></a>. To ensure full interoperability and well-defined
        behavior, <a href="../../../../../../libs/asio/index.html" target="_top">Boost.Asio</a> imposes
        requirements on the implementation of composed operations. These classes
        and functions make it easier to develop initiating functions and their composed
        operations:
      </p>
<div class="table">
<a name="beast.using_io.writing_composed_operations.asynchronous_helpers"></a><p class="title"><b>Table 1.12. Asynchronous Helpers</b></p>
<div class="table-contents"><table class="table" summary="Asynchronous Helpers">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__async_base.html" title="async_base"><code class="computeroutput"><span class="identifier">async_base</span></code></a> <a class="link" href="../ref/boost__beast__stable_async_base.html" title="stable_async_base"><code class="computeroutput"><span class="identifier">stable_async_base</span></code></a>
                </p>
              </td>
<td>
                <p>
                  This class is designed to be used as a base class when authoring
                  composed asynchronous operations expressed as an intermediate completion
                  handler. This eliminates the need for the extensive boilerplate
                  to propagate the associated executor, associated allocator, and
                  legacy completion handler hooks.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__allocate_stable.html" title="allocate_stable"><code class="computeroutput"><span class="identifier">allocate_stable</span></code></a>
                </p>
              </td>
<td>
                <p>
                  For composed operation algorithms which need stable storage for
                  temporary objects, this function may be used. Memory for the stable
                  storage is allocated using the allocator associated with the final
                  completion handler. The implementation automatically destroys the
                  temporary object before the final completion handler is invoked,
                  or when the intermediate completion handler is destroyed.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__bind_handler.html" title="bind_handler"><code class="computeroutput"><span class="identifier">bind_handler</span></code></a>
                </p>
              </td>
<td>
                <p>
                  This function creates a new handler which, when invoked, calls
                  the original handler with the list of bound arguments. Any parameters
                  passed in the invocation will be substituted for placeholders present
                  in the list of bound arguments. Parameters which are not matched
                  to placeholders are silently discarded.
                </p>
                <p>
                  The passed handler and arguments are forwarded into the returned
                  handler, whose associated allocator and associated executor will
                  be the same as those of the original handler.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__bind_front_handler.html" title="bind_front_handler"><code class="computeroutput"><span class="identifier">bind_front_handler</span></code></a>
                </p>
              </td>
<td>
                <p>
                  This function creates a new handler which, when invoked, calls
                  the original handler with the list of bound arguments, along with
                  the list of invoked arguments at either the front or the back of
                  the argument list. Placeholders are not supported.
                </p>
                <p>
                  The passed handler and arguments are forwarded into the returned
                  handler, whose associated allocator and associated executor will
                  will be the same as those of the original handler.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__saved_handler.html" title="saved_handler"><code class="computeroutput"><span class="identifier">saved_handler</span></code></a>
                </p>
              </td>
<td>
                <p>
                  This wrapper safely stores a completion handler so it may be invoked
                  later, allowing an implementation to "pause" an operation
                  until some condition is met.
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie
      Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="files.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_io.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="writing_composed_operations/echo.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
